Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 3 - Window Manager Reference / Window Manager Functions

Defining Your Own Window Definition Function /

MyWindowDefProc

CHANGED WITH THE APPEARANCE MANAGER

Your window definition function is responsible for

• drawing the window frame
• reporting the region where mouse-down events occur
• calculating the window's structure region and content region
• drawing the size box
• resizing the window frame when the user drags the size box
• reporting the window's features or the location of a specific window region
• performing any customized initialization or disposal tasks

If you wish to define new, nonstandard windows for your application, you must write a window definition function and store it in a resource file as a resource of type 'WDEF'.

The Window Manager declares the type for an application-defined window definition function as follows:

typedef pascal long (*WindowDefProcPtr)(
                                         short varCode, 
                                         WindowPtr theWindow, 
                                         short message, 
                                         long param);

The Window Manager defines the data type WindowDefUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr WindowDefUPP;

You typically use the NewWindowDefProc macro like this:

WindowDefUPP myWindowDefUPP;
myWindowDefUPP = NewWindowDefProc(MyWindow);

You typically use the CallWindowDefProc macro like this:

CallWindowDefProc(myWindowDefUPP, varCode, theWindow, message, param);

Here's how to declare the function MyWindowDefProc:

pascal long MyWindowDef(
                     short varCode,
                     WindowPtr theWindow,
                     short message,
                     long param);

varCode

The window's variation code.

theWindow

A pointer to the window's window structure.

message

A value indicating the task to be performed. The message parameter contains one of the values defined in "Messages". The subsections that follow explain each of these tasks in detail.

param

Data associated with the task specified by the message parameter. If the task requires no data, this parameter is ignored.

function result

Your window definition function should perform whatever task is specified by the message parameter and return a function result, if appropriate. If the task performed requires no result code, return 0.

Messages

The Window Manager passes a value defined by one of these constants in the message parameter of your window definition function to specify the action your function must perform. Other messages are reserved for internal use by the system.

enum {
   wDraw                 = 0, 
   wHit                  = 1, 
   wCalcRgns             = 2, 
   wNew                  = 3, 
   wDispose              = 4, 
   wGrow                 = 5, 
   wDrawGIcon            = 6,
   kWindowMsgGetFeatures = 7,
   kWindowMsgGetRegion   = 8
};

Constant descriptions

wDraw

Draw the window's frame.

wHit

Report the location of a mouse-down event.

wCalcRgns

Calculate the structure region and the content region.

wNew

Perform additional initialization.

wDispose

Perform additional disposal.

wGrow

Draw the dotted outline of the window that you see during a resizing operation.

wDrawGIcon

Draw the outlines for the size box and the scroll bar.

kWindowMsgGetFeatures

Report the window's features.

kWindowMsgGetRegion

Report the location of a specific window region.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

Only the following messages will be sent to your window definition function:

enum {
   wDraw             = 0, 
   wHit              = 1, 
   wCalcRgns         = 2, 
   wNew              = 3, 
   wDispose          = 4, 
   wGrow             = 5, 
   wDrawGIcon        = 6
} ;

Drawing the Window Frame

When the Window Manager passes wDraw in the message parameter, your window definition function should respond by drawing the window frame in the current graphics port (which is the Window Manager port). The window part code to be drawn will be passed in the param parameter of your window definition function.

Your window definition function should perform the following steps:

• Change the current port from the WMgrPort to the WMgrCPort to allow the system to draw in the full range of RGB colors.
• Update the pen attributes, text attributes, and bkPat fields in the WMgrCPort to the values of the corresponding fields in the WMgrPort. The Window Manager automatically transfers the vis and clip regions.

Note

The parallelism of the WMgrPort and the WMgrCPort is maintained only by the window definition functions. All window definition functions that draw in the WMgrPort should follow the steps listed above even if the changed fields do not affect their operation.

You must make certain checks to determine exactly how to draw the frame. If the value of the visible field in the window structure is false, you should do nothing; otherwise, you should examine the param parameter and the status flags in the window structure:

• If the value of param is 0, draw the entire window frame (including the size box, if your window definition function incorporates the size box into the frame).
• If the value of param is 0 and the hilited field in the window structure is true, highlight the frame to show that the window is active.
  • If the value of the goAwayFlag field in the window structure is also true, draw a close box in the window frame.
  • If the value of the spareFlag field in the window structure is also true, draw a zoom box in the window frame.

• If the value of the param parameter is wInGoAway, add highlighting to, or remove it from, the window's close box.
• If the value of the param parameter is wInZoom, add highlighting to, or remove it from, the window's zoom box.
• If the value of the param parameter is wInCollapseBox, add highlighting to, or remove it from, the window's collapse box.

You need to maintain your own state flag to determine whether the close, zoom, or collapse box is to be drawn as highlighted. Typically, you clear this state flag whenever you draw the entire frame, and you set it before drawing whenever your application is called to draw just the close, zoom, or collapse box. If the flag is set, you draw the box in a highlighted state.

The window frame typically, but not necessarily, includes the window's title, which should be displayed in the system font and system font size. The Window Manager port is already set to use the system font and system font size.

Note

Nothing drawn outside the window's structure region will be visible.

Your window definition function should return 0 as the function result for this message.

Reporting the Region of a Mouse-Down Event

When the Window Manager passes wHit in the message parameter, your window definition function should respond by reporting the region of the specified mouse-down event. The mouse location (in global coordinates) of the window frame will be passed into the param parameter of your window definition function. The vertical coordinate is in the high-order word of the parameter, and the horizontal coordinate is in the low-order word.

In response to the wHit message, your window definition function should return one of the following constants:

enum {
   wNoHit         = 0, 
   wInContent     = 1, 
   wInDrag        = 2, 
   wInGrow        = 3, 
   wInGoAway      = 4, 
   wInZoomIn      = 5, 
   wInZoomOut     = 6,  
   wInCollapseBox = 9
};

Constant descriptions

wNoHit

The mouse-down event did not occur in the content region or the drag region of any active or inactive window or in the close, size, zoom, or collapse box of an active window. The return value wNoHit might also mean that the point isn't in the window. The standard window definition functions, for example, return wNoHit if the point is in the window frame but not in the title bar.

wInContent

The mouse-down event occurred in the content region of an active or inactive window (with the exception of the size box).

wInDrag

The mouse-down event occurred in the drag region of an active or inactive window.

wInGrow

The mouse-down occurred in the size box of an active window.

wInGoAway

The mouse-down event occurred in the close box of an active window.

wInZoomIn

The mouse-down event occurred in the zoom box of an active window that is currently in the standard state.

wInZoomOut

The mouse-down event occurred in the zoom box of an active window that is currently in the user state.

wInCollapseBox

The mouse-down event occurred in the collapse box of an active window.

Return the constants wInGrow, wInGoAway, wInZoomIn, wInZoomOut, and wInCollapseBox only if the window is active--by convention, the size box, close box, zoom box, and collapse box aren't drawn if the window is inactive. In an inactive document window, for example, a mouse-down event in the part of the title bar that would contain the close box if the window were active is reported as wInDrag.

Calculating Regions

When the Window Manager passes wCalcRgns in the message parameter, your window definition function should respond by calculating the window's structure and content regions based on the current graphics port's port rectangle. These regions, whose handles are in the strucRgn and contRgn fields of the window structure, are in global coordinates. The Window Manager requests this operation only if the window is visible. The mouse location (in global coordinates) of the window frame will be passed into the param parameter of your window definition function.

Your window definition function should call IsWindowCollapsed to determine its collapse state. Then your window definition function can modify its structure and content regions as appropriate. Typically, a window's content region is empty in a collapsed state.

WARNING

When you calculate regions for your own type of window, do not alter the clip region or the visible region of the Window Manager port. The Window Manager and QuickDraw take care of this for you. Altering the Window Manager port's clip region or visible region may damage other windows.

Your window definition function should return 0 as the function result for this message.

Performing Additional Window Initialization

When the Window Manager passes wNew in the message parameter, your window definition function should respond by performing any initialization that it may require. If the content region has an unusual shape, for example, you might allocate memory for the region and store the region handle in the dataHandle field of the window structure. The initialization function for a standard document window creates the wStateData structure for storing zooming data.

Your window definition function should ignore the param parameter and return 0 as the function result for this message.

Performing Additional Window Disposal Actions

When the Window Manager passes wDispose in the message parameter, your window definition function should respond by performing any additional tasks necessary for disposing of a window. You might, for example, release memory that was allocated by the initialization function. The dispose function for a standard document window disposes of the wStateData structure.

Your window definition function should ignore the param parameter and return 0 as the function result for this message.

Drawing the Window's Grow Image

When the Window Manager passes wGrow in the message parameter, your window definition function should respond to being resized by drawing a dotted outline of the window in the current graphics port in the pen pattern and mode. (The pen pattern and mode are set up--as gray and notPatXor--to conform to Appearance-compliant human interface guidelines.)

A rectangle (in global coordinates) whose upper-left corner is aligned with the port rectangle of the window's graphics port is passed into the param parameter of your window definition function. Your grow image should be sized appropriately for the specified rectangle. As the user drags the mouse, the Window Manager sends repeated wGrow messages, so that you can change your grow image to match the changing mouse location.

DrawGrowIcon draws a dotted (gray) outline of the window and also the lines delimiting the title bar, size box, and scroll bar areas.

Your window definition function should return 0 as the function result for this message.

Drawing the Size Box

When the Window Manager passes wDrawGIcon in the message parameter, your window definition function should respond by drawing the size box in the content region if the window is active. If the window is inactive, your window definition function should draw whatever is appropriate to show that the window cannot currently be sized. Your window definition function may also draw scroll bar delimiter lines. Your window definition function should ignore the param parameter.

If the size box is located in the window frame, draw the size box in response to a wDraw message, not a wDrawGIcon message.

Your window definition function should return 0 as the function result for this message.

Reporting Window Features

When the Window Manager passes kWindowMsgGetFeatures in the message parameter, your window definition function should respond by setting the param parameter to reflect the features that your window supports. The value passed back in the param parameter should be comprised of one or more of the following values:

enum{
   kWindowCanGrow            = (1 << 0),
   kWindowCanZoom            = (1 << 1),
   kWindowCanCollapse        = (1 << 2),
   kWindowIsModal            = (1 << 3),
   kWindowCanGetWindowRegion = (1 << 4),
   kWindowIsAlert            = (1 << 5),
   kWindowHasTitleBar        = (1 << 6),
};

Constant descriptions

kWindowCanGrow

If this bit (bit 0) is set, the window has a grow box (may not be visible).

kWindowCanZoom

If this bit (bit 1) is set, the window has a zoom box (may not be visible).

kWindowCanCollapse

If this bit (bit 2) is set, the window has a collapse box.

kWindowIsModal

If this bit (bit 3) is set, the window should behave as modal.

kWindowCanGetWindowRegion

If this bit (bit 4) is set, the window supports a call to GetWindowRegion.

kWindowIsAlert

If this bit (bit 5) is set, the window is an alert box (may be movable or not). When this constant is added to kWindowIsModal, the user should be able to switch out of the application and move the alert box.

kWindowHasTitleBar

If this bit (bit 6) is set, the window has a title bar.

Your window definition function should return 1 as the function result for this message.

Returning the Location of Window Regions

When the Window Manager passes kWindowMsgGetRegion in the message parameter, your window definition function should respond by returning the location (in global coordinates) of the specified window region. A pointer to a window region structure will be passed in the param parameter.

The window region structure is a structure of type GetWindowRegionRec.

struct GetWindowRegionRec {
   RgnHandle      winRgn;
   WindowRegionCoderegionCode;
};
typedef struct GetWindowRegionRec GetWindowRegionRec;
typedef GetWindowRegionRec *GetWindowRegionPtr;

Field Description

winRgn

A handle to a window region based on the value specified in the regionCode field. Modify this region.

regionCode

A value representing a given window region; see "Window Region Constants".

Your window definition function should return an operating system status (OSStatus) message as the function result for this message. The result code errWindowRgnInvalid indicates that the window region passed in was not valid.